<!DOCTYPE html>
<html prefix="og: http://ogp.me/ns#">
<head>
  <meta charset="UTF-8">
  <title>Configuration API</title>
  <link data-turbolinks-track="true" href="../../../assets/application-b86a2086c99917c6bf2a9d74b4038381.css" media="all" rel="stylesheet" />
  <script data-turbolinks-track="true" src="../../../assets/application-c3106c6fe52ccec6f26495730a478cca.js"></script>
  <meta content="authenticity_token" name="csrf-param" />
<meta content="yzXUiWH6GiCHbvbJOg7usjzA7LawyxwB+oJHEcWTOIM=" name="csrf-token" />
  <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-3769691-35', 'atom.io');
  ga('send', 'pageview');

</script>

  <meta property="og:url" content="https://atom.io/" />
<meta property="og:site_name" content="Atom" />
<meta property="og:title" content="A hackable text editor for the 21st Century" />
<meta property="og:description" content="At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it." />
<meta property="og:type" content="website" />
<meta property="og:author" content='https://www.facebook.com/GitHub' />
<meta property="og:image" content="http://og.github.com/atom-logo/atom-logo@1200x1200.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="1200" />
<meta property="og:image" content="http://og.github.com/atom-mark/atom-mark@1200x630.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

  <meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:site" content="@AtomEditor" />
<meta property="twitter:creator" content='@github' />
<meta property="twitter:title" content="Atom" />
<meta property="twitter:description" content="A hackable text editor for the 21st Century" />
<meta property="twitter:image:src" content="http://og.github.com/atom-logo/atom-logo@1200x630.png" />
<meta property="twitter:image:width" content="1200" />
<meta property="twitter:image:height" content="630" />

  <link rel="shortcut icon" href="../../../favicon.ico"/>
</head>
<body>

  <div class="footer-push">
    
    

    <header class="header">
  <div class="wrapper">
    <h1 title="Atom">
      <a href="../../../index.html" class="logo"></a>
    </h1>

    <ul class="navigation">
      <li><a class="" href="../../../packages.html">Packages</a></li>
      <li><a class="is-selected" href="../../latest/index.html">Documentation</a></li>
      <li><a href="http://blog.atom.io">Blog</a></li>
      <li><a href="../../../faq.html">FAQ</a></li>
      <li><a class="" href="https://atom.io/contact">Contact</a></li>
    </ul>
  </div>
</header>


    <div class="wrapper documents content-push">
  <div class="columns">
    <div class="column main-column markdown">
        <h2>
<a name="configuration-api" href="configuration.html#configuration-api"></a>Configuration API</h2>

<h3>
<a name="reading-config-settings" href="configuration.html#reading-config-settings"></a>Reading Config Settings</h3>

<p>If you are writing a package that you want to make configurable, you'll need to
read config settings via the <code>atom.config</code> global. You can read the current
value of a namespaced config key with <code>atom.config.get</code>:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> read a value with `config.get`</span></span></span></div><div class="line"><span class="source coffee"><span class="variable other readwrite instance coffee"><span>@showInvisibles</span></span><span class="meta brace round coffee"><span>(</span><span>)</span></span><span> </span><span class="keyword control coffee"><span>if</span></span><span> atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>config</span><span class="meta delimiter method period coffee"><span>.</span></span><span>get </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>editor.showInvisibles</span><span class="punctuation definition string end coffee"><span>"</span></span></span></span></div></pre>

<p>Or you can use the <code>::observeConfig</code> to track changes from any view object.</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="meta class coffee"><span class="storage type class coffee"><span>class</span></span><span> </span><span class="entity name type class coffee"><span>MyView</span></span><span> </span><span class="keyword control inheritance coffee"><span>extends</span></span><span> </span><span class="entity other inherited-class coffee"><span>View</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>initializ</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable other readwrite instance coffee"><span>@observeConfig</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>editor.fontSize</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="meta inline function coffee"><span class="variable parameter function coffee"><span>()</span></span><span> </span><span class="storage type function coffee"><span>=&gt;</span></span></span></span></div><div class="line"><span class="source coffee"><span>      </span><span class="variable other readwrite instance coffee"><span>@adjustFontSize</span></span><span class="meta brace round coffee"><span>(</span><span>)</span></span></span></div></pre>

<p>The <code>::observeConfig</code> method will call the given callback immediately with the
current value for the specified key path, and it will also call it in the future
whenever the value of that key path changes.</p>

<p>Subscriptions made with <code>observeConfig</code> are automatically canceled when the
view is removed. You can cancel config subscriptions manually via the
<code>unobserveConfig</code> method.</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span>view1</span><span class="meta delimiter method period coffee"><span>.</span></span><span>unobserveConfig</span><span class="meta brace round coffee"><span>(</span><span>)</span></span><span> </span><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> unobserve all properties</span></span></span></div></pre>

<p>You can add the ability to observe config values to non-view classes by
extending their prototype with the <code>ConfigObserver</code> mixin:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="meta variable assignment destructured coffee"><span class="keyword operator coffee"><span>{</span></span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>ConfigObserver</span></span></span><span class="keyword operator coffee"><span>} =</span></span></span><span> </span><span class="support function coffee"><span>require</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>atom</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span> </span></span></div><div class="line"><span class="source coffee"><span class="meta class coffee"><span class="storage type class coffee"><span>class</span></span><span> </span><span class="entity name type class coffee"><span>MyClass</span></span></span></span></div><div class="line"><span class="source coffee"><span>  ConfigObserver</span><span class="meta delimiter method period coffee"><span>.</span></span><span>includeInto</span><span class="meta brace round coffee"><span>(</span></span><span class="variable language coffee"><span>this</span></span><span class="meta brace round coffee"><span>)</span></span></span></div><div class="line"><span class="source coffee"><span> </span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>constructo</span><span class="entity name function coffee"><span>r</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable other readwrite instance coffee"><span>@observeConfig</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>editor.showInvisibles</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="storage type function coffee"><span>-&gt;</span></span><span> </span><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> ...</span></span></span></div><div class="line"><span class="source coffee"><span> </span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>destro</span><span class="entity name function coffee"><span>y</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable other readwrite instance coffee"><span>@unobserveConfig</span></span><span class="meta brace round coffee"><span>(</span><span>)</span></span></span></div></pre>

<h3>
<a name="writing-config-settings" href="configuration.html#writing-config-settings"></a>Writing Config Settings</h3>

<p>The <code>atom.config</code> database is populated on startup from <code>~/.atom/config.cson</code>,
but you can programmatically write to it with <code>atom.config.set</code>:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> basic key update</span></span></span></div><div class="line"><span class="source coffee"><span>atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>config</span><span class="meta delimiter method period coffee"><span>.</span></span><span>set</span><span class="meta brace round coffee"><span>(</span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>core.showInvisibles</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="constant language boolean true coffee"><span>true</span></span><span class="meta brace round coffee"><span>)</span></span></span></div></pre>

<p>You should never mutate the value of a config key, because that would circumvent
the notification of observers. You can however use methods like <code>pushAtKeyPath</code>,
<code>unshiftAtKeyPath</code>, and <code>removeAtKeyPath</code> to manipulate mutable config values.</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span>atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>config</span><span class="meta delimiter method period coffee"><span>.</span></span><span>pushAtKeyPath</span><span class="meta brace round coffee"><span>(</span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>core.disabledPackages</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>wrap-guide</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta brace round coffee"><span>)</span></span></span></div><div class="line"><span class="source coffee"><span>atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>config</span><span class="meta delimiter method period coffee"><span>.</span></span><span>removeAtKeyPath</span><span class="meta brace round coffee"><span>(</span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>core.disabledPackages</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>terminal</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta brace round coffee"><span>)</span></span></span></div></pre>

<p>You can also use <code>setDefaults</code>, which will assign default values for keys that
are always overridden by values assigned with <code>set</code>. Defaults are not written
out to the the <code>config.json</code> file to prevent it from becoming cluttered.</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span>atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>config</span><span class="meta delimiter method period coffee"><span>.</span></span><span>setDefaults</span><span class="meta brace round coffee"><span>(</span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>editor</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>fontSize</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="constant numeric coffee"><span>18</span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>showInvisibles</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="constant language boolean true coffee"><span>true</span></span><span class="meta brace round coffee"><span>)</span></span></span></div></pre>
    </div>
    <div class="column sidebar documents-toc">
      <select class="js-doc-version-switcher version-switcher">
  <option selected="selected" value="v0.69.0">v0.69.0</option>
<option value="v0.68.0">v0.68.0</option>
<option value="v0.67.0">v0.67.0</option>
<option value="v0.66.0">v0.66.0</option>
<option value="v0.65.0">v0.65.0</option>
<option value="v0.64.0">v0.64.0</option>
<option value="v0.63.0">v0.63.0</option>
<option value="v0.62.0">v0.62.0</option>
<option value="v0.61.0">v0.61.0</option>
<option value="v0.60.0">v0.60.0</option>
<option value="v0.59.0">v0.59.0</option>
<option value="v0.58.0">v0.58.0</option>
<option value="v0.57.0">v0.57.0</option>
<option value="v0.56.0">v0.56.0</option>
<option value="v0.55.0">v0.55.0</option>
<option value="v0.54.0">v0.54.0</option>
<option value="v0.53.0">v0.53.0</option>
<option value="v0.51.0">v0.51.0</option>
<option value="v0.50.0">v0.50.0</option>
<option value="v0.49.0">v0.49.0</option>
<option value="v0.48.0">v0.48.0</option>
<option value="v0.47.0">v0.47.0</option>
<option value="v0.46.0">v0.46.0</option>
<option value="v0.45.0">v0.45.0</option>
<option value="v0.44.0">v0.44.0</option>
<option value="v0.41.0">v0.41.0</option>
<option value="v0.40.0">v0.40.0</option>
<option value="0.52.0">0.52.0</option>
</select>


      <ul class="navigation">
        <li><a href="" class="is-selected">Documentation</a></li>
        <li><a href="../../api/v0.69.0/api/index.html">API</a></li>
      </ul>

      <hr />

      <form accept-charset="UTF-8" action="/docs/v0.69.0/search" method="get"><div style="margin:0;padding:0;display:inline"><input name="utf8" type="hidden" value="&#x2713;" /></div>
        <input class="sidebar-search-field" id="q" name="q" placeholder="Search documentation" type="text" value="" />
</form>
      <h2>
<a name="guides" href="configuration.html#guides"></a>Guides</h2>

<ul>
<li><a href="../getting-started.html">Getting Started</a></li>
<li><a href="../customizing-atom.html">Customizing Atom</a></li>
<li><a href="../creating-a-package.html">Creating a Package</a></li>
<li><a href="../creating-a-theme.html">Creating a Theme</a></li>
<li><a href="../publishing-a-package.html">Publishing a Package</a></li>
<li><a href="../converting-a-text-mate-bundle.html">Converting a TextMate Bundle</a></li>
<li><a href="../converting-a-text-mate-theme.html">Converting a TextMate Theme</a></li>
<li><a href="../contributing.html">Contributing</a></li>
</ul><h3>
<a name="advanced-topics" href="configuration.html#advanced-topics"></a>Advanced Topics</h3>

<ul>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="keymaps.html">Keymaps</a></li>
<li><a href="serialization.html">Serialization</a></li>
<li><a href="view-system.html">View System</a></li>
</ul>
    </div>
  </div>
</div>


    <div class="footer-pad"></div>
  </div>

  <footer>
  <div class="footer">
    <div class="wrapper">
      <ul class="footer-left">
        <li><a href="../../../terms.html">Terms of Use</a></li>
          <li><a href="https://atom.io/login">Sign in</a></li>
      </ul>

      <div class="footer-right">
        <a href="https://github.com"><span class="octicon octicon-code"></span> with <span class="octicon octicon-heart"></span> by <span class="octicon octicon-logo-github"></span></a>
      </div>
    </div>
  </div>
</footer>

</body>
</html>
